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ABOUT THIS CHAPTER 


TextEdit is the part of the Toolbox that handles basic text formatting and 
editing capabilities in a Macintosh application. This chapter describes the 
TextEdit routines and data types in detail as well as the enhanced version of 
TextEdit for the Macintosh Plus, the Macintosh SE and Macintosh II. The new 
TextEdit routines allow text attributes such as font, size, style, and color to 
vary from one character to another. The changes are backward compatible with 
earlier Macintosh versions: all existing programs using TextEdit routines should 
still work. The new TextEdit is also fully compatible with the Script Manager. 


You should already be familiar with: 


¢ the basic concepts and structures behind QuickDraw, particularly 
points, rectangles, grafPorts, fonts, and character style 

¢ the Toolbox Event Manager the Window Manager, particularly update 
and activate events 
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ABOUT TEXTEDIT 


Note: 


The extensions to TextEdit described in this chapter were originally 
documented in Inside Macintosh, Volumes IV and V. As such, the Volume 
IV information refers to the 128K ROM and System file version 3.2 and 
later, while the Volume V information refers to the Macintosh SE and 
Macintosh II ROMs and System file version 4.1 and later. The sections 
of this chapter that cover these extensions are so noted. 


TextEdit is a set of routines and data types that provide the basic text editing 
and formatting capabilities needed in an application. These capabilities 


include: 
« inserting new text 
e deleting characters that are backspaced over 
e translating mouse activity into text selection 
« scrolling text within a window 
e deleting selected text and possibly inserting it elsewhere, or 


copying text without deleting it 


The TextEdit routines follow the Macintosh User Interface Guidelines; using them 
ensures that your application will present a consistent user interface. The 
Dialog Manager uses TextEdit for text editing in dialog boxes. 


TextEdit supports these standard features: 


e 


Note: 


Selecting text by clicking and dragging with the mouse, double-clicking 
to select words. To TextEdit, a word is any series of printing characters, 
excluding spaces (ASCII code $20) but including nonbreaking spaces 
(ASCII code $CA). 

Extending or shortening the selection by Shift-clicking. 

Inverse highlighting of the current text selection, or display of a 
blinking vertical bar at the insertion point. 

Word wraparound, which prevents a word from being split between lines 
when text is drawn. 

Cutting (or copying) and pasting within an application via the 
Clipboard. TextEdit puts text you cut or copy into the TextEdit scrap. 


The TextEdit scrap is used only by TextEdit; it's not the same as 
the "desk scrap" used by the Scrap Manager. To support cutting and 
pasting between applications, or between applications and desk 

accessories, you must transfer information between the two scraps. 


Although TextEdit is useful for many standard text editing operations, there are 


some 


e 


additional features that it doesn't support. TextEdit does not support: 


the use of more than one font or stylistic variation in a single 

block of text 

fully justified text (text aligned with both the left and right margins) 
"intelligent" cut and paste (adjusting spaces between words during 
cutting and pasting) 

tabs 
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TextEdit also provides "hooks" for implementing some features such as automatic 
scrolling or a more precise definition of a word. 


Note: The extensions to TextEdit described in the following paragraphs were 
Originally documented in Inside Macintosh, Volume IV. As such, this 


information refers to the 128K ROMs and System file version 3.2 and 
later. 


When used with the System file version 3.0 or later, TextEdit also automatically 
supports the movement of the insertion point with the Macintosh Plus arrow keys; 
this is described the Macintosh User Interface Guidelines chapter. 


Warning: Command—arrow key combinations are not supported by TextEdit 


and must be handled by your application. Selection expansion 
must also be handled by your application. 
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DATA STRUCTURES 


Note: The extensions to TextEdit described in the following paragraphs were 
Originally documented in Inside Macintosh, Volume V. As such, this 
information refers to the Macintosh SE and Macintosh II ROMs and System 
file version 4.1 and later. 


The structure and size of the edit record are unchanged in the enhanced version 
of TextEdit, but a few of its fields are interpreted in different ways. All 
records have a 32K maximum size. A new data structure, the style record, has 
been introduced to carry the style information for the edit record's text, along 
with various subsidiary data structures: the style run, the style table and its 
style elements, the line-height table and its line-height elements, and the 
null-style record. In addition, there is the text style record for passing 
style information to and from TextEdit routines, and the style scrap record for 
writing style information to the desk scrap. 


The Edit Record 


Note: The information on the Edit Record described in the following 
paragraphs was originally documented in Inside Macintosh, Volume I. 


To edit text on the screen, TextEdit needs to know where and how to display the 
text, where to store the text, and other information related to editing. This 
display, storage, and editing information is contained in an edit record that 
defines the complete editing environment. The data type of an edit record is 
called TERec. 


You prepare to edit text by specifying a destination rectangle in which to draw 
the text and a view rectangle in which the text will be visible. TextEdit 
incorporates the rectangles and the drawing environment of the current grafPort 
into an edit record, and returns a handle of type TEHandle to the record: 


TYPE TEPtr 
TEHandle 


“TERec; 
“TEPtr; 


Most of the text editing routines require you to pass this handle as a 
parameter. 


In addition to the two rectangles and a description of the drawing environment, 
the edit record also contains: 


« a handle to the text to be edited 

* a pointer to the grafPort in which the text is displayed 

e the current selection range, which determines exactly which 
characters will be affected by the next editing operation 

¢ the justification of the text, as left, right, or center 


The special terms introduced here are described in detail below. 
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For most operations, you don't need to know the exact structure of an edit 
record; TextEdit routines access the record for you. However, to support some 
operations, such as automatic scrolling, you need to access the fields of the 
edit record directly. The structure of an edit record is given below. 


Note: The extensions to TextEdit described in the following paragraph were 
Originally documented in Inside Macintosh, Volume IV. As such, this 
information refers to the 128K ROMs and System file version 3.2 and 
later. 


TextEdit now installs a default click loop routine in the edit record that 
Supports automatic scrolling; you still need, however, to update the scroll 
bars. If automatic scrolling is enabled, this routine checks to see if the mouse 
has been dragged out of the view rectangle; if it has, the routine scrolls the 
text using TEPinScroll. The amount by which the text is scrolled, whether 
horizontally or vertically, is determined by the lineHeight field of the edit 
record. 


The Destination and View Rectangles 


Note: The information on the Destination and View Rectangles described in 
the following paragraphs was originally documented in Inside Macintosh, 
Volume I. 


The destination rectangle is the rectangle in which the text is drawn. The view 
rectangle is the rectangle within which the text is actually visible. In other 
words, the view of the text drawn in the destination rectangle is clipped to the 
view rectangle (see Figure 1). 


This document is This document is full 
Full of choice bits choice bits of readline 
oF reading ; material. Mote that is 
material. Hote ——§+ | within the destination 

rechangle, but visible 


Figure 1-Destination and View Rectangles 
Figure 1—Destination and View Rectangles 


You specify both rectangles in the local coordinates of the grafPort. To ensure 
that the first and last characters in each line are legible in a document 
window, you may want to inset the destination rectangle at least four pixels 
from the left and right edges of the grafPort's portRect (20 pixels from the 
right edge if there's a scroll bar or size box). 
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Edit operations may of course lengthen or shorten the text. If the text becomes 
too long to be enclosed by the destination rectangle, it's simply drawn beyond 
the bottom. In other words, you can think of the destination rectangle as 
bottomless—its sides determine the beginning and end of each line of text, and 
its top determines the position of the first Line. 


Normally, at the right edge of the destination rectangle, the text automatically 
wraps around to the left edge to begin a new line. A new line also begins where 
explicitly specified by a Return character in the text. Word wraparound ensures 
that no word is ever split between lines unless it's too long to fit entirely on 
one line, in which case it's split at the right edge of the destination 
rectangle. 


The Selection Range 


In the text editing environment, a character position is an index into the text, 
with position 0 corresponding to the first character. The edit record includes 
fields for character positions that specify the beginning and end of the current 
selection range, which is the series of characters where the next editing 
operation will occur. For example, the procedures that cut or copy from the text 
of an edit record do so to the current selection range. 


The selection range, which is inversely highlighted when the window is active, 
extends from the beginning character position to the end character position. 
Figure 2 shows a selection range between positions 3 and 8, consisting of five 
characters (the character at position 8 isn't included). The end position of a 
selection range may be 1 greater than the position of the last character of the 
text, so that the selection range can include the last character. 


If the selection range is empty—that is, its beginning and end positions are the 
same—that position is the text's insertion point, the position where characters 
will be inserted. By default, it's marked with a blinking caret. If, for 
example, the insertion point is as illustrated in Figure 2 and the inserted 
characters are “edit ", the text will read "the edit insertion point". 
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selection raluge 
hevinning at position 3 
and ending at position ¢ 


012 9 45 & F #@ 9 Wil 12 1914 15 ibd? 18 19 


the linsertion point 


Insertion point 
at position 4 


Figure 2-Selection Range and Insertion Point 
Figure 2—Selection Range and Insertion Point 


Note: We use the word caret here generically, to mean a symbol 
indicating where something is to be inserted; the specific 
symbol is a vertical bar ( | ). 


If you call a procedure to insert characters when there's a selection range of 
one or more characters rather than an insertion point, the editing procedure 
automatically deletes the selection range and replaces it with an insertion 
point before inserting the characters. 


Justification 


TextEdit allows you to specify the justification of the lines of text, that is, 
their horizontal placement with respect to the left and right edges of the 
destination rectangle. The different types of justification supported by 
TextEdit are illustrated in Figure 3. 


e Left justification aligns the text with the left edge of the 
destination rectangle. This is the default type of justification. 

¢ Center justification centers each line of text between the left 
and right edges of the destination rectangle. 

e Right justification aligns the text with the right edge of the 
destination rectangle. 
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Thit is an example 
of left 
Justification. Hee 
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aligned with the 
left edge of the 
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This is an example 
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how the text is 
aligned with the 
right edge of the 


rectaturle rectangle rectangle 


Figure 3—Justification 
Figure 3—Justification 
Note: Trailing spaces on a line are ignored for justification. For 
example, "Fred" and "Fred " will be aligned identically. (Leading 
spaces are not ignored. ) 
TextEdit provides three predefined constants for setting the justification: 
CONST teJustLeft 


teJustCenter 
tejJustRight 


The TERec Data Type 


The structure of an edit record is given here. Some TextEdit features are 
available only if you access fields of the edit record directly. 


TYPE TERec = RECORD 


destRect: Rect; {destination rectangle} 
viewRect: Rect; {view rectangle} 
selRect: Rect; {used from assembly Language} 


lineHeight: INTEGER; {for line spacing} 
fontAscent: INTEGER; {caret/highlighting position} 


selPoint: Point; {used from assembly language} 
selStart: INTEGER; {start of selection range} 
selEnd: INTEGER; {end of selection range} 
active: INTEGER; {used internally} 

wordBreak: ProcPtr; {for word break routine} 
clikLoop: ProcPtr; {for click loop routine} 
clickTime: LONGINT; {used internally} 

clickLoc: INTEGER; {used internally} 


caretTime: LONGINT; {used internally} 
caretState: INTEGER; {used internally} 


just: INTEGER; {justification of text} 
teLength: INTEGER; {length of text} 
hText: Handle; {text to be edited} 


recalBack: INTEGER; {used internally} 
recalLines: INTEGER; {used internally} 
clikStuff: INTEGER; {used internally} 


crOnly: INTEGER; {if <Q, new line at Return only} 
txFont: INTEGER; {text font} 
txFace: Style; {character style} 
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txMode: INTEGER; {pen mode} 


txSize: INTEGER; {font size} 

inPort: GrafPtr; {grafPort} 

highHook: ProcPtr; {used from assembly Language} 
caretHook: ProcPtr; {used from assembly Language} 
nLines: INTEGER; {number of lines} 


lineStarts: ARRAY[@..16000] OF INTEGER 
{positions of line starts} 
END; 


Warning: Don't change any of the fields marked "used internally"—these 
exist solely for internal use among the TextEdit routines. 


The destRect and viewRect fields specify the destination and view rectangles. 


The LineHeight and fontAscent fields have to do with the vertical spacing of the 
lines of text, and where the caret or highlighting of the selection range is 
drawn relative to the text. The fontAscent field specifies how far above the 
base line the pen is positioned to begin drawing the caret or highlighting. For 
single-spaced text, this is the ascent of the text in pixels (the height of the 
tallest characters in the font from the base line). The lineHeight field 
specifies the vertical distance from the ascent line of one line of text down to 
the ascent line of the next. For single-spaced text, this is the same as the 
font size, but in pixels. The values of the lineHeight and fontAscent fields for 
Single-spaced text are shown in Figure 4. For more information on fonts, see the 
Font Manager chapter. 


ascent Line —+ 


. oo 
hase line —+ i 
ascent line —+ z 


> Font Ascent 


base line —+ 


Figure 4—LineHeizht and Font Ascent 
Figure 4—LineHeight and FontAscent 


If you want to change the vertical spacing of the text, you should change both 
the LineHeight and fontAscent fields by the same amount, otherwise the placement 
of the caret or highlighting of the selection range may not look right. For 
example, to double the line spacing, add the value of lineHeight to both fields. 
(This doesn't change the size of the characters; it affects only the spacing 
between lines.) If you change the size of the text, you should also change these 
fields; you can get font measurements you'll need with the QuickDraw procedure 
GetFontInfo. 


Assembly-language note: The selPoint field (whose assembly-language offset 
is named teSelPoint) contains the point selected 
with the mouse, in the local coordinates of the 
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current grafPort. You'll need this for hit-testing 
if you use the routine pointed to by the global 
variable TEDoText (see "Advanced Routines" in the 
"TextEdit Routines" section). 


The selStart and selEnd fields specify the character positions of the beginning 
and end of the selection range. Remember that character position 0 refers to the 
first character, and that the end of a selection range can be 1 greater than the 
position of the last character of the text. 


The wordBreak field lets you change TextEdit's definition of a word, and the 
clikLoop field lets you implement automatic scrolling. These two fields are 
described in separate sections below. 


The just field specifies the justification of the text. (See "Justification", 
above. ) 


The teLength field contains the number of characters in the text to be edited 
(the maximum length is 32K bytes). The hText field is a handle to the text. You 
can directly change the text of an edit record by changing these two fields. 


The crOnly field specifies whether or not text wraps around at the right edge of 
the destination rectangle, as shown in Figure 5. If crOnly is positive, text 
does wrap around. If crOnly is negative, text does not wrap around at the edge 
of the destination rectangle, and new lines are specified explicitly by Return 
characters only. This is faster than word wraparound, and is useful in an 
application similar to a programming-language editor, where you may not want a 
single line of code to be split onto two lines. 


There's a Return There's a Return charac 
character at the end But mot at the end of th 
ob this line. 


But mot at the end of 
this line. Or this line. 


new line at Return pew line at Return 
characters aud edge of characters only 
destination rectangle 


Figure 5—New Lines 
Figure 5—New Lines 


The txFont, txFace, txMode, and txSize fields specify the font, character style, 
pen mode, and font size, respectively, of all the text in the edit record. (See 
the QuickDraw chapter for details about these characteristics.) If you change 
one of these values, the entire text of this edit record will have the new 
characteristics when it's redrawn. If you change the txSize field, remember to 
change the lineHeight and fontAscent fields, too. 


The inPort field contains a pointer to the grafPort associated with this edit 
record. 
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Note: When printing, the inPort field must be set to the Printing Manager's 
grafPort (TPPrPort*.gPort). 


Assembly-language note: The highHook and caretHook fields—at the offsets 
teHiHook and teCarHook in assembly language—contain 
the addresses of routines that deal with text 
highlighting and the caret. These routines pass 
parameters in registers; the application must save 
and restore the registers. 


If you store the address of a routine in teHiHook, 
that routine will be used instead of the QuickDraw 
procedure InvertRect whenever a selection range is 

to be highlighted. The routine can destroy the 
contents of registers AQ, Al, DO, D1, and D2. On 
entry, A3 is a pointer to a locked edit record; the 
stack contains the rectangle enclosing the text being 
highlighted. For example, if you store the address of 
the following routine in teHiHook, selection ranges 
will be underlined instead of inverted: 


UnderHigh 
MOVE.L (SP) , AQ ;get address of 
; rectangle to be 
; highlighted 
MOVE bottom(AQ),top(AQ0) ;make the top 
; coordinate equal 
; to the bottom 
SUBQ #1, top(AQ) ; coordinate - 1 
_InverRect ;invert the 
; resulting 
; rectangle 
RTS 


The routine whose address is stored in teCarHook acts 
exactly the same way as the teHiHook routine, but on 
the caret instead of the selection highlighting, 
allowing you to change the appearance of the caret. 
The routine is called with the stack containing the 
rectangle that encloses the caret. 


The nLines field contains the number of lines in the text. The lineStarts array 
contains the character position of the first character in each line. It's 
declared to have 16001 elements to comply with Pascal range checking; it's 
actually a dynamic data structure having only as many elements as needed. You 
shouldn't change the elements of lineStarts. 


Note: The extensions to TextEdit described in the following paragraphs were 
Originally documented in Inside Macintosh, Volume V. As such, this 
information refers to the Macintosh SE and Macintosh II ROMs and System 
file version 4.1 and later. 


In the enhanced version of TextEdit, most fields of the edit record have the 
same meanings as in the old TextEdit, with the following exceptions: 


txSize Used as a flag telling whether the edit record has style 
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information associated with it: 


>0 Old-style edit record; all text set in a single font, size, 
and face; all fields (including txSize itself) have their 
old, natural meanings. 


-1 Edit record has associated style information; the txFont and 
txFace fields have new meanings as described below. 


txFont, txFace Combine to hold a handle to the associated style record 
(see "The Style Record" below). Use new routines 
GetStylHandle and SetStylHandle to access or change this 
handle in Pascal. 


LineHeight Controls whether vertical spacing is fixed or may vary 
fontAscent from line to line, depending on specific text styles: 
>0 Fixed line height or font ascent, as before. 
-1 Line height or font ascent calculated independently for 


each line, based on maximum value for any individual style 
on that Line. 


The new routine TEStylNew, which creates a new edit record with style 
information, sets txSize, lineHeight, and fontAscent to -1, allocates a style 
record, and stores a handle to the style record in the txFont and txFace fields. 
The old routine TENew still creates a new edit record without style information, 
initializing these fields from the current graphics port as before. 


The WordBreak Field 


Note: The information on the WordBreak Field described in the following 
paragraphs was originally documented in Inside Macintosh, Volume I. 


The wordBreak field of an edit record lets you specify the record's word break 
routine—the routine that determines the "word" that's highlighted when the user 
double-clicks in the text, and the position at which text is wrapped around at 
the end of a line. The default routine breaks words at any character with an 
ASCII value of $20 or less (the space character or nonprinting control 
characters). 


The word break routine must have two parameters and return a Boolean value. This 
is how you would declare one named MyWordBreak: 


FUNCTION MyWordBreak (text: Ptr; charPos: INTEGER) : BOOLEAN; 


The function should return TRUE to break a word at the character at position 
charPos in the specified text, or FALSE not to break there. From Pascal, you 
must call the SetWordBreak procedure to set the wordBreak field so that your 
routine will be used. 


Assembly-language note: You can set this field to point to your own 
assembly-language word break routine. The registers 
must contain the following: 


On entry AQ: pointer to text 
DO: character position (word) 
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On exit Z (zero) condition code: 
0 to break at specified character 
1 not to break there 


The ClikLoop Field 


The clikLoop field of an edit record lets you specify a routine that will be 
called repeatedly (by the TEClick procedure, described below) as long as the 
mouse button is held down within the text. You can use this to implement the 
automatic scrolling of text when the user is making a selection and drags the 
cursor out of the view rectangle. 


The click loop routine has no parameters and returns a Boolean value. You could 
declare a click loop routine named MyClikLoop like this: 


FUNCTION MyClikLoop : BOOLEAN; 


The function should return TRUE. From Pascal, you must call the SetClikLoop 
procedure to set the clikLoop field so that TextEdit will call your routine. 


Warning: Returning FALSE from your click loop routine tells the TEClick 
procedure that the mouse button has been released, which aborts 
TEClick. 


Assembly-language note: Your routine should set register DO to 1, and 
preserve register D2. (Returning 0 in register 
DO aborts TEClick. ) 


An automatic scrolling routine might check the mouse location, and call a 
scrolling routine if the mouse location is outside the view rectangle. (The 
scrolling routine can be the same routine that the Control Manager function 
TrackControl calls.) The handle to the current edit record should be kept as a 
global variable so the scrolling routine can access it. 


The Style Record 


Note: The extensions to TextEdit described in the following paragraphs were 
Originally documented in Inside Macintosh, Volume V. As such, this 
information refers to the Macintosh SE and Macintosh II ROMs and System 
file version 4.1 and later. 


The style record, located via a handle kept in the txFont and txFace fields of 
the edit record, specifies the styles for the edit record's text. The text is 
divided into runs of consecutive characters in the same style, summarized in a 
table in the runs field of the style record. Each entry in this table gives the 
starting character position of a run and an index into the style table 
(described in the next section). The length of the run is found by subtracting 
its start position from that of the next entry in the table. A dummy entry at 
the end of the table delimits the length of the last run; its start position is 
equal to the overall number of characters in the text, plus 1. 


TYPE 
TEStyleHandle = *TEStylePtr; 
TEStylePtr = “TEStyleRec; 


@ SpInside Macintosh * Version 1.0 * November 1989 « Apple Computer 
TEXTEDIT ¢ 15 of 43 


TEStyleRec 


StyleRun = 


END; 


= RECORD 
nRuns: INTEGER; {number of style runs} 
nStyles: INTEGER; {number of distinct styles } 
{ stored in style table} 
styleTab: STHandle; {handle to style table} 
LhTab: LHHandle; {handle to line-height table} 
teRefCon: LONGINT; {reserved for application use} 


nullStyle: nullSTHandle; {handle to style set } 
{ at null selection} 
runs: ARRAY [0..0] OF StyleRun 
END; 


RECORD 
startChar: INTEGER; {starting character position} 
styleIndex: INTEGER {index in style table} 


Field descriptions 


nRuns 
nStyles 


styleTab 
LhTab 


teRefCon 
nullStyle 


runs 


The nRuns field specifies the number of style runs in the text. 
The nStyles field contains the number of distinct styles used 

in the text; this forms the size of the style table. 

The StyleTab field contains a handle to the style table (see 

"The Style Table" below). 

The lhTab field contains a handle to the line-height table 

(see "The Line-Height Table" below). 

The teRefCon field is a reference constant for use by applications. 
The nullStyle field contains a handle to a data structure used 
to store the style information for a null selection. 

The runs field contains an indefinite-length array of style runs. 


The Style Table 


The style table contains one entry for each distinct style used in an edit 
record's text. The size of the table is given by the nStyles field of the style 
record. There is no duplication; each style appears exactly once in the table. 
A reference count tells how many times each style is used within the text. 


TYPE 

STHandle = “STPtr; 

STPtr = “TEStyleTable; 

TEStyleTable = ARRAY [0..0] OF STElement; 

STELement = RECORD 
stCount: INTEGER; {number of runs in this style} 
stHeight: INTEGER; {line height} 
stAscent: INTEGER; {font ascent} 
stFont: INTEGER; {font (family) number} 
stFace: Style; {character style} 
stSize: INTEGER; {size in points} 
stColor: RGBColor {absolute (RGB) color} 

END; 


Field descriptions 
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stCount The stCount field contains a reference count of character 
runs using this style. 
stHeight The stHeight field contains the line height for this style, 


in points. 

stAscent The stAscent field contains the font ascent for this style, 
in points. 

stFont The stFont field is the font (family) number. 

stFace The stFace field is the character style (bold, italic, and 
so forth). 

stSize The stSize field is the text size in points. 

stColor The stColor field is the RGB color; see the Color Manager 


chapter for further information. 


The Line-Height Table 


The line-height table holds vertical spacing information for an edit record's 
text. This table parallels the lineStarts table in the edit record itself. Its 
length is given by the edit record's nLines field plus 1 for a dummy entry at 
the end, just as the line starts array ends with a dummy entry that has the same 
value as the length of the text. The table's contents are recalculated whenever 
the line starts themselves are recalculated with TECalText, or whenever an 
editing action causes recalibration. 


The line-height table is used only if the lineHeight and fontAscent fields in 
the edit record are negative; positive values in those fields specify fixed 
vertical spacing, overriding the information in the table. 


TYPE 
LHHandle = “LHPtr; 
LHPtr = “LHTable; 
LHTable = ARRAY [0..0] OF LHElement; 
LHElement = RECORD 
lUhHeight: INTEGER; {maximum height in line} 
LhAscent: INTEGER {maximum ascent in line} 


END; 
Field descriptions 


LhHeight The lhHeight field contains the line height in points; 
this is the maximum value for any individual style in a Line. 


LhAscent The lhAscent field contains the font ascent in points; 
this is the maximum value for any individual style in a Line. 


If you want, you can override TextEdit's line-height calculation and store your 
own height and ascent values into the line-height table. Any table entry with 
the high bit set in the lhHeight field will be used as-is (both height and 
ascent), overriding whatever values TextEdit would have used. The high bit of 
LhHeight is masked out to arrive at the true line height, but the high bit of 
lhAscent is not masked, so you should never set it; the one in lhHeight serves 
as a flag for both fields. Notice that you can selectively set some lines for 
yourself and let TextEdit do the rest for you. This technique is intended to be 
used for static, unchanging text, such as in text boxes; if you use it on text 
that can change dynamically, be sure to readjust your line-height values 
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whenever the line breaks in the text are recalculated. Otherwise, if new lines 
are created as a result of a text insertion, their line heights and ascents will 
be computed by TextEdit. 


The Null-Style Record 


The null-style record is used to store the style information for a null 
selection. If TESetStyle is called when setStart equals setEnd, the input style 
information is stored in the nullStyle handle. The nStyles field of nullScrap is 
set to 1, and the style information is stored as the ScrpSTElement. If text is 
then entered (pasted, inserted, or typed), the style is entered into the runs 
array, and nStyles is reset to 0. The nStyles field is also reset if the 
selection offsets are changed (by TEClick, for example). 


TYPE 
NullSTHandle = “NullSTPtr; 
NullSTPtr = “NullSTRec; 
NullSTRec = RECORD 
TEReserved: LONGINT; {reserved for future } 
{ expansion} 
nullScrap: STScrpHandle {handle to scrap style } 
{ table} 
END; 
Field descriptions 
teReserved The teReserved field is reserved for future expansion. 
nullScrap The nullScrap field contains a handle to the scrap style table. 


Text Styles 


Text style records are used for communicating style information between the 
application program and the TextEdit routines. They carry the same information 
as the STElement records in the style table, but without the reference count, 
line height, and font ascent: 


TYPE 
TextStyle = RECORD 
tsFont: INTEGER; {Font (family) number} 
tsFace: Style; {Character style} 
tsSize: INTEGER; {Size in points} 
tsColor: RGBColor {Absolute (RGB) color} 
END; 


Field descriptions 


tsFont The tsFont field is the font (family) number. 

tsFace The tsFace field is the character style (bold, italic, and so forth). 
tsSize The tsSize field is the text size in points. 

tsColor The tsColor field contains the RGB color; see the Color Manager 


chapter for further information. 
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The Style Scrap 


A new scrap type, 'styl', is used for storing style information in the desk 
scrap along with the old 'TEXT' scrap. The format of the style scrap is defined 
by a style scrap record: 


TYPE 
StScrpHandle = *“StScrpPtr; 
StScrpPtr = “StScrpRec; 
StScrpRec = RECORD 
scrpNStyles: INTEGER; {number of distinct } 


{ styles in scrap} 
scrpStyleTab: ScrpSTTable {table of styles for scrap} 
END; 


Field descriptions 


scrpNStyles The scrpNStyles field is the number of distinct styles 
used in text; this forms the size of the style table. 


scrpSTTable The scrpSTTable is the table of text styles: see the data 
structure shown below. 


Unlike the main style table for an edit record, the table in the style scrap may 
contain duplicate elements; the entries in the table correspond one-to-one with 
the character runs in the text. The scrpStartChar field of each entry gives the 
starting character position for the run. 


The ScrpSTTable is a separate data structure defined for style records in the 
scrap. Its format is: 


TYPE 

ScrpSTTable = array [0..0] of ScrpSTElement; 

ScrpSTElement = RECORD 
scrpStartChar: LONGINT; {offset to start of style} 
scrpHeight: INTEGER; {line height} 
scrpAscent: INTEGER; {font ascent} 
scrpFont: INTEGER; {font (family) number} 
scrpFace: Style; {character style} 
scrpSize: INTEGER; {size in points} 
scrpColor: RGBColor; {absolute (RGB) color} 

END; 


Field descriptions 


scrpStartChar The scrpStartChar field is the offset to the beginning 
of a style record in the scrap. 


scrpHeight The scrpHeight field contains the line height. 

scrpAscent The scrpAscent field contains the font ascent. 

scrpFont The scrpFont is the font's family number. 

scrpFace The scrpFace is the character style for the style scrap. 
scrpSize The scrpSize field contains the size in points. 

scrpColor The scrpColor field contains the RGB color for the style scrap. 
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USING TEXTEDIT 


Note: The information on Using TextEdit described in the following 
paragraphs was originally documented in Inside Macintosh, Volume I. 


Before using TextEdit, you must initialize QuickDraw, the Font Manager, and the 
Window Manager, in that order. 


The first TextEdit routine to call is the initialization procedure TEInit. Call 
TENew to allocate an edit record; it returns a handle to the record. Most of the 
text editing routines require you to pass this handle as a parameter. 


When you've finished working with the text of an edit record, you can get a 
handle to the text as a packed array of characters with the TEGetText function. 


Note: To convert text from an edit record to a Pascal string, you can use 
the Dialog Manager procedure GetIText, passing it the text handle 
from the edit record. 


When you're completely done with an edit record and want to dispose of it, call 
TEDispose. 


To make a blinking caret appear at the insertion point, call the TEIdle 
procedure as often as possible (at least once each time through the main event 
loop); if it's not called often enough, the caret will blink irregularly. 


Note: To change the cursor to an I-beam, you can call the Toolbox Utility 
function GetCursor and the QuickDraw procedure SetCursor. The resource 
ID for the I-beam cursor is defined in the Toolbox Utilities as the 
constant iBeamCursor. 


When a mouse-down event occurs in the view rectangle (and the window is active) 
call the TEClick procedure. TEClick controls the placement and highlighting of 
the selection range, including supporting use of the Shift key to make extended 
selections. 


Key-down, auto-key, and mouse events that pertain to text editing can be handled 
by several TextEdit procedures: 


e TEKey inserts characters and deletes characters backspaced over. 

e TECut transfers the selection range to the TextEdit scrap, removing 
the selection range from the text. 

¢ TEPaste inserts the contents of the TextEdit scrap. By calling TECut, 
changing the insertion point, and then calling TEPaste, you can perform 
a "cut and paste" operation, moving text from one place to another. 

e TECopy copies the selection range to the TextEdit scrap. By calling 
TECopy, changing the insertion point, and then calling TEPaste, you 
can make multiple copies of text. 

« TEDelete removes the selection range (without transferring it to the 
scrap). You can use TEDelete to implement the Clear command. 

e TEInsert inserts specified text. You can use this to combine two or 
more documents. TEDelete and TEInsert do not modify the scrap, so 
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they're useful for implementing the Undo command. 


After each editing procedure, TextEdit redraws the text if necessary from the 
insertion point to the end of the text. You never have to set the selection 
range or insertion point yourself; TEClick and the editing procedures leave it 
where it should be. If you want to modify the selection range directly, 
however—to highlight an initial default name or value, for example—you can use 
the TESetSelect procedure. 


To implement cutting and pasting of text between different applications, or 
between applications and desk accessories, you need to transfer the text between 
the TextEdit scrap (which is a private scrap used only by TextEdit) and the 
Scrap Manager's desk scrap. You can do this using the functions TEFromScrap and 
TEToScrap. (See the Scrap Manager chapter for more information about scrap 
handling. ) 


When an update event is reported for a text editing window, call TEUpdate—along 
with the Window Manager procedures BeginUpdate and EndUpdate—to redraw the text. 


Note: After changing any fields of the edit record that affect the 
appearance of the text, you should call the Window Manager procedure 
InvalRect (hTE**.viewRect) so that the text will be updated. 


The procedures TEActivate and TEDeactivate must be called each time GetNextEvent 
reports an activate event for a text editing window. TEActivate simply 
highlights the selection range or displays a caret at the insertion point; 
TEDeactivate unhighlights the selection range or removes the caret. 


To specify the justification of the text, you can use TESetJust. If you change 
the justification, be sure to call InvalRect so the text will be updated. 


To scroll text within the view rectangle, you can use the TEScroll procedure. 


Note: The extensions to TextEdit described in the following paragraphs were 
Originally documented in Inside Macintosh, Volume IV. As such, this 
information refers to the 128K ROMs and System file version 3.2 and 
later. 


Automatic scrolling of text (when the user is making a selection and drags the 
cursor out of the view rectangle) is now supported by TextEdit. 


To enable and disable automatic scrolling, call the procedure TEAutoView. 
TESelView will, if automatic scrolling is enabled, automatically scroll the 
selection range into view. TEPinScroll scrolls text within the view rectangle 
but stops when the last line comes into view. 


Note: When enabled, automatic scrolling can occur in response to 
TESelView, TEKey, TEPaste, TEDelete, and TESetSelect. 


Note: The information on TESetText described in the following 
paragraphs was originally documented in Inside Macintosh, Volume I. 


The TESetText procedure lets you change the text being edited. For example, if 
your application has several separate pieces of text that must be edited one at 
a time, you don't have to allocate an edit record for each of them. Allocate a 
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single edit record, and then use TESetText to change the text. (This is the 
method used in dialog boxes.) 


Note: TESetText actually makes a copy of the text to be edited. Advanced 
programmers can save space by storing a handle to the text in the 
hText field of the edit record itself, then calling TECalText to 
recalculate the beginning of each line. 


If you ever want to draw noneditable text in any given rectangle, you can use 
the TextBox procedure. 


If you've written your own word break or click loop routine in Pascal, you must 
call the SetWordBreak or SetClikLoop procedure to install your routine so 
TextEdit will use it. 
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CUTTING AND PASTING 


Note: The extensions to TextEdit described in the following paragraphs were 
Originally documented in Inside Macintosh, Volume V. As such, this 
information refers to the Macintosh SE and Macintosh II ROMs and System 
file version 4.1 and later. 


For new TextEdit records created using TEStylNew, the routines TECut and TECopy 
will write both the text and its associated style information directly to the 
desk scrap, under scrap types 'TEXT' and ‘'styl', respectively. (For 
compatibility with existing applications, they also write a handle to the text 
to the old global TEScrapHandle.) For old TextEdit records, TECopy and TEPaste 
will work as they did before, copying and pasting via the private TextEdit scrap 
only. 


A new routine, TEStylPaste, reads both text and style back from the desk scrap 
and pastes them into the document at the current selection range or insertion 
point. The old TEPaste reads the text only, ignoring any style information 
found in the scrap; instead it uses the style of the first character in the 
selection range being replaced, or that of the preceding character if the 
selection is an insertion point. (TEStylPaste defaults to the same behavior if 
it doesn't find a 'styl' entry in the desk scrap.) The old routines TEFromScrap 
and TEToScrap, for transferring text between the desk and internal scraps, are 
no longer needed, but are still supported for backward compatibility. The 
GetStylScrap and TEStylInsert routines can now be used to access the text and 
style information associated with a given selection without destroying the 
current contents of the desk scrap. 
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TEXTEDIT ROUTINES 


Note: The information on TextEdit Routines described in the following 
paragraphs was originally documented in Inside Macintosh, Volume I. 
Those routines which were added with Styled TextEdit in Volume V 
are marked as such. 


The Macintosh Plus, Macintosh SE, and Macintosh II versions of TextEdit support 
all previous TextEdit routines, as well as the new routines described below. 


Assembly-language note: ALL but two of the new routines share a single 
trap, TEDispatch ($A83D). The routines are 
distinguished by an integer routine selector 
passed on the stack, after the last argument: 


TEStylPaste 
TESetStyle 
TEReplaceStyle 
TEGetStyle 
GetStylHandle 
SetStylHandle 
GetStylScrap 
TEStyliInsert 
TEGetPoint 
TEGetHeight 


OONDUBWNEF © 


The Pascal interface supplies the routine selectors 
automatically, as do the macros for calling these 
routines from assembly language. The remaining two 
new TextEdit routines have traps of their own: 
_TEStylNew ($A83E) and TEGetOffset ($A83C). 


Initialization and Allocation 
PROCEDURE TEInit; 


TEInit initializes TextEdit by allocating a handle for the TextEdit scrap. The 
scrap is initially empty. Call this procedure once and only once at the 
beginning of your program. 


Note: You should call TEInit even if your application doesn't use TextEdit, 
so that desk accessories and dialog and alert boxes will work correctly. 


FUNCTION TENew (destRect,viewRect: Rect) : TEHandle; 


TENew allocates a handle for text, creates and initializes an edit record, and 
returns a handle to the new edit record. DestRect and viewRect are the 
destination and view rectangles, respectively. Both rectangles are specified in 
the current grafPort's coordinates. The destination rectangle must always be at 
least as wide as the first character drawn (about 20 pixels is a good minimum 
width). The view rectangle must not be empty (for example, don't make its right 
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edge less than its left edge if you don't want any text visible—-specify a 
rectangle off the screen instead). 


Call TENew once for every edit record you want allocated. The edit record 


incorporates the drawing environment of the grafPort, and is initialized for 
left-justified, single-spaced text with an insertion point at character position 
0. 


Note: The caret won't appear until you call TEActivate. 

FUNCTION TEStylNew (destRect,viewRect: Rect) : TEHandle; [Styled TextEdit] 

The TEStylNew routine creates a new-style edit record with associated style 
information. It initializes the new record's txSize, lineHeight, and fontAscent 
fields to -1; allocates a style record and stores a handle to it in the txFont 
and txFace fields. 


PROCEDURE TEDispose (hTE: TEHandle); 


TEDispose releases the memory allocated for the edit record and text specified 
by hTE. Call this procedure when you're completely through with an edit record. 


Accessing the Text or Style Information of an Edit Record 
PROCEDURE TESetText (text: Ptr; Length: LONGINT; hTE: TEHandle); 


TESetText incorporates a copy of the specified text into the edit record 
specified by hTE. The text parameter points to the text, and the length 
parameter indicates the number of characters in the text. The selection range is 
set to an insertion point at the end of the text. TESetText doesn't affect the 
text drawn in the destination rectangle, so call InvalRect afterward if 
necessary. TESetText doesn't dispose of any text currently in the edit record. 


FUNCTION TEGetText (hTE: TEHandle) : CharsHandle; 
TEGetText returns a handle to the text of the specified edit record. The result 


is the same as the handle in the hText field of the edit record, but has the 
CharsHandle data type, which is defined as: 


TYPE CharsHandle = “CharsPtr; 
CharsPtr = “Chars; 
Chars = PACKED ARRAY[@..32000] OF CHAR; 


You can get the length of the text from the teLength field of the edit record. 


PROCEDURE TEGetStyle (offset: INTEGER; VAR theStyle: TextStyle; 
VAR LineHeight, fontAscent: INTEGER; hTE: TEHandle) ; 
[Styled TextEdit] 


The TEGetStyle procedure returns the style information, including line height 
and font ascent, associated with a given character in an edit record's text. 
For an old-style edit record, it returns the record's global text 
characteristics. 
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PROCEDURE SetStylHandle (theHandle: TEStyleHandle; hTE: TEHandle) ; 
[Styled TextEdit] 


The SetStylHandle procedure sets an edit record's style handle, stored in the 
txFont and txFace fields. SetStylHandle has no effect on an old-style edit 
record. Applications should always use SetStylHandle rather than manipulating 
the fields of the edit record directly. 


FUNCTION GetStylHandle (hTE: TEHandle) : TEStyleHandle; [Styled TextEdit] 

The GetStylHandle function gets an edit record's style handle, stored in the 
txFont and txFace fields. GetStylHandle returns NIL when used with an old-style 
edit record. Applications should always use this function rather than 
manipulating the fields of the edit record directly. 


Note: See Macintosh Technical Note #207 for information on TEContinuousStyle 
and TENumStyles. 


eeeClick on the X-Ref button, and refer to Technical Note #207.¢ee 


Insertion Point and Selection Range 
PROCEDURE TEIdle (hTE: TEHandle); 


Call TEIdle repeatedly to make a blinking caret appear at the insertion point 
(if any) in the text specified by hTE. (The caret appears only when the window 
containing that text is active, of course.) TextEdit observes a minimum blink 
interval: No matter how often you call TEIdle, the time between blinks will 
never be less than the minimum interval. 


Note: The initial minimum blink interval setting is 32 ticks. The user 
can adjust this setting with the Control Panel desk accessory. 


To provide a constant frequency of blinking, you should call TEIdle as often as 
possible—at least once each time through your main event loop. Call it more than 
once if your application does an unusually large amount of processing each time 
through the Loop. 


Note: You actually need to call TEIdle only when the window containing 
the text is active. 


PROCEDURE TEClick (pt: Point; extend: BOOLEAN; hTE: TEHandle); 


TEClick controls the placement and highlighting of the selection range as 
determined by mouse events. Call TEClick whenever a mouse-down event occurs in 
the view rectangle of the edit record specified by hTE, and the window 
associated with that edit record is active. TEClick keeps control until the 
mouse button is released. Pt is the mouse location (in local coordinates) at the 
time the button was pressed, obtainable from the event record. 


Note: Use the QuickDraw procedure GlobalToLocal to convert the global 
coordinates of the mouse location given in the event record to 
the local coordinate system for pt. 


@ SpInside Macintosh ¢ Version 1.0 * November 1989 ¢ Apple Computer 
TEXTEDIT ¢ 26 of 43 


Pass TRUE for the extend parameter if the Event Manager indicates that the Shift 
key was held down at the time of the click (to extend the selection). 


TEClick unhighlights the old selection range unless the selection range is being 
extended. If the mouse moves, meaning that a drag is occurring, TEClick expands 
or shortens the selection range accordingly. In the case of a double-click, the 
word under the cursor becomes the selection range; dragging expands or shortens 
the selection a word at a time. 


PROCEDURE TESetSelect (selStart,selEnd: LONGINT; hTE: TEHandle); 


TESetSelect sets the selection range to the text between selStart and selEnd in 
the text specified by hTE. The old selection range is unhighlighted, and the new 
one is highlighted. If selStart equals selEnd, the selection range is an 
insertion point, and a caret is displayed. 


SelEnd and selStart can range from 0 to 32767. If selEnd is anywhere beyond the 
last character of the text, the position just past the last character is used. 


PROCEDURE TEActivate (hTE: TEHandle); 


TEActivate highlights the selection range in the view rectangle of the edit 
record specified by hTE. If the selection range is an insertion point, it 
displays a caret there. This procedure should be called every time the Toolbox 
Event Manager function GetNextEvent reports that the window containing the edit 
record has become active. 


PROCEDURE TEDeactivate (hTE: TEHandle); 


TEDeactivate unhighlights the selection range in the view rectangle of the edit 
record specified by hTE. If the selection range is an insertion point, it 
removes the caret. This procedure should be called every time the Toolbox Event 
Manager function GetNextEvent reports that the window containing the edit record 
has become inactive. 


Editing 
PROCEDURE TEKey (key: CHAR; hTE: TEHandle) ; 


TEKey replaces the selection range in the text specified by hTE with the 
character given by the key parameter, and leaves an insertion point just past 
the inserted character. If the selection range is an insertion point, TEKey just 
inserts the character there. If the key parameter contains a Backspace 
character, the selection range or the character immediately to the left of the 
insertion point is deleted. TEKey redraws the text as necessary. Call TEKey 
every time the Toolbox Event Manager function GetNextEvent reports a keyboard 
event that your application decides should be handled by TextEdit. 


Note: TEKey inserts every character passed in the key parameter, so it's 
up to your application to filter out all characters that aren't 
actual text (such as keys typed in conjunction with the Command key). 


PROCEDURE TECut (hTE: TEHandle) ; 
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TECut removes the selection range from the text specified by hTE and places it 
in the TextEdit scrap. The text is redrawn as necessary. Anything previously in 
the scrap is deleted. (See Figure 6.) If the selection range is an insertion 
point, the scrap is emptied. 


Before TECut: | This ic Ea good ilvstration. a 


text TextEdit scrap 
After TECut: | This is a good Wuetration. probably 
text TextEdit scrap 


Figure 6—Cutting 
Figure 6—Cutting 
PROCEDURE TECopy (hTE: TEHandle); 


TECopy copies the selection range from the text specified by hTE into the 
TextEdit scrap. Anything previously in the scrap is deleted. The selection range 
is not deleted. If the selection range is an insertion point, the scrap is 
emptied. 


PROCEDURE TEPaste (hTE: TEHandle); 


TEPaste replaces the selection range in the text specified by hTE with the 
contents of the TextEdit scrap, and leaves an insertion point just past the 
inserted text. (See Figure 7.) The text is redrawn as necessary. If the scrap is 
empty, the selection range is deleted. If the selection range is an insertion 
point, TEPaste just inserts the scrap there. 
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Before TE Cut: | Bag before you leap | 


text TextEdit scrap 

After TEC ut: [before you, before youlesp = foot, | 
TextEdit scrap 

Before TEPaste: | before aa free, | 
TextEdit scrap 

After TEPaste: | before you look, [before wou took, Ieep wok, | 
TextEdit scrap 


Figure 7-Cutting and Pasting 
Figure 7—Cutting and Pasting 


PROCEDURE TEStylPaste (hTE: TEHandle); [Styled TextEdit] 


The TEStylPaste procedure pastes text from the desk scrap into the edit 
record's text at the current insertion point or replaces the current selection. 
The text is styled according to the style information found in the desk scrap; 
if there is none, it is given the same style as the first character of the 
replaced selection (or that of the preceding character if the selection is an 
insertion point). In an old-style edit record, just the text is pasted without 
its accompanying style. 


PROCEDURE TEDelete (hTE: TEHandle); 


TEDelete removes the selection range from the text specified by hTE, and redraws 
the text as necessary. TEDelete is the same as TECut (above) except that it 
doesn't transfer the selection range to the scrap. If the selection range is an 
insertion point, nothing happens. 


PROCEDURE TEInsert (text: Ptr; length: LONGINT; hTE: TEHandle); 


TEInsert takes the specified text and inserts it just before the selection range 
into the text indicated by hTE, redrawing the text as necessary. The text 
parameter points to the text to be inserted, and the length parameter indicates 
the number of characters to be inserted. TEInsert doesn't affect either the 
current selection range or the scrap. 


PROCEDURE TEStylInsert (text: Ptr; length: LONGINT; hST: stScrpHandle; 
hTE: TEHandle); [Styled TextEdit] 


The TEStylInsert procedure takes the specified text and inserts it just before 
the selection range into the text indicated by hTE, redrawing the text as 


@ SpInside Macintosh ¢ Version 1.0 * November 1989 * Apple Computer 
TEXTEDIT ¢ 29 of 43 


necessary. If hST is not NIL and hTE is a TextEdit record created using 
TEStylNew, the style information indicated by hST will also be inserted to 
correspond with the inserted text. When hST is NIL and/or hTE has not been 
created using TEStylNew, there is no difference between this procedure and 
TEInsert. TEStylInsert does not affect either the current selection range or the 
scrap. 


PROCEDURE TEReplaceStyle (mode: INTEGER; oldStyle,newStyle: TextStyle; 
redraw: BOOLEAN; hTE: TEHandle); [Styled TextEdit] 


The TEReplaceStyle procedure replaces the style specified by oldStyle with that 
given by newStyle within the current selection. (It has no effect on an old- 
style edit record.) The mode parameter takes the same values as TESetStyle 
(above), except that addSize has no meaning here. ALl styles for which the 
combination of attributes designated by mode have the values given by oldStyle 
are changed to have the corresponding values from newStyle instead. Style 
changes are made directly to the style-table elements within the table itself. 
If mode = doAll, newStyle simply replaces oldStyle outright. 


PROCEDURE TESetStyle (mode: INTEGER; newStyle: TextStyle; redraw: BOOLEAN; 
hTE: TEHandle); [Styled TextEdit] 


The TESetStyle procedure sets the style of the current selection to that 
specified by newStyle. ( It has no effect on an old-style edit record.) The 
mode parameter controls which style attributes to set; it may be any additive 
combination of the following constants: 


CONST 
doFont = 1; {set font (family) number} 
doFace = 2; {set character style} 
doSize = 4; {set type size} 
doColor = 8; {set color} 
doALl = 15; {set all attributes} 
addSize = 16; {adjust type size} 


In the last case (addSize), the value of newStyle.tsSize is added to all type 
Sizes within the current selection instead of replacing them; this value may be 
either positive or negative. (If present, addSize overrides doSize.) If redraw 
= TRUE, the affected text will be redrawn in the new style. 


Text Display and Scrolling 
PROCEDURE TESetJust (just: INTEGER, hTE: TEHandle); 


TESetjJust sets the justification of the text specified by hTE to just. TextEdit 
provides three predefined constants for setting justification: 


CONST teJustLeft 
teJustCenter 
teJustRight 


By default, text is left-justified. If you change the justification, call 
InvalRect after TESetJust, so the text will be redrawn with the new 
justification. 
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PROCEDURE TEUpdate (rUpdate: Rect; hTE: TEHandle); 


TEUpdate draws the text specified by hTE within the rectangle specified by 
rUpdate (given in the coordinates of the current grafPort). Call TEUpdate every 
time the Toolbox Event Manager function GetNextEvent reports an update event for 
a text editing window—after you call the Window Manager procedure BeginUpdate, 
and before you call EndUpdate. 


Normally you'll do the following when an update event occurs: 


BeginUpdate(myWindow) ; 

EraseRect (myWindow’.portRect) ; 
TEUpdate(myWindow*%.portRect,hTE) ; 
EndUpdate(myWindow) 


If you don't include the EraseRect call, the caret may sometimes remain visible 
when the window is deactivated. 


PROCEDURE TextBox (text: Ptr; length: LONGINT; box: Rect; just: INTEGER); 


TextBox draws the specified text in the rectangle indicated by the box 
parameter, with justification just. (See "Justification" under "Edit Records". ) 
The text parameter points to the text, and the length parameter indicates the 
number of characters to draw. The rectangle is specified in local coordinates, 
and must be at least as wide as the first character drawn (a good rule of thumb 
is to make it at least 20 pixels wide). TextBox creates its own edit record, 
which it deletes when it's finished with it, so the text it draws cannot be 
edited. 


For example: 


str := 'String in a box'; 

SetRect(r,100,100,200, 200) ; 

TextBox (POINTER(ORD(@str)+1),LENGTH(str),r,teJustCenter) ; 
FrameRect (r) 


Because Pascal strings start with a length byte, you must advance the pointer 
one position past the beginning of the string to point to the start of the text. 


[ Note by DTC 2003-12-31: 

Instead of using POINTER(ORD(@str)+1) above, use the following instead which is 
shorter and much easier to type and does not assume that the byte after the 
string's starting address is the actual start of the string data: @str[1] ] 


PROCEDURE TEScroll (dh,dv: INTEGER; hTE: TEHandle) ; 


TEScroll scrolls the text within the view rectangle of the specified edit record 
by the number of pixels specified in the dh and dv parameters. The edit record 
is specified by the hTE parameter. Positive dh and dv values move the text right 
and down, respectively, and negative values move the text left and up. For 
example, 


TEScroll(0, -hTE**. LineHeight , hTE) 
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scrolls the text up one line. Remember that you scroll text up when the user 
clicks in the scroll arrow pointing down. The destination rectangle is offset by 
the amount you scroll. 


Note: To implement automatic scrolling, you store the address of a routine 
in the clikLoop field of the edit record, as described above under 
"The TERec Data Type". 


PROCEDURE TESelView (hTE: TEHandle); [Volume IV addition] 


If automatic scrolling has been enabled (by a call to TEAutoView, described 
below), TESelView makes sure that the selection range is visible, scrolling it 
into the view rectangle if necessary. If automatic scrolling is disabled, 
TESelView does nothing. 


Note: The top left of the insertion is scrolled into view; if text is 
being displayed in a rectangle that's not tall enough, automatic 
scrolling could cause the text to jump up and down at times. 

PROCEDURE TEPinScroll (dh,dv: INTEGER; hTE: TEHandle); [Volume IV addition] 


TEPinScroll is similar to TEScroll except that it stops scrolling when the last 
line scrolls into the view rectangle. 


PROCEDURE TEAutoView (auto: BOOLEAN; hTE: TEHandle); [Volume IV addition] 
TEAutoView enables and disables automatic scrolling of text in the edit record 


specified by hTe. If the auto parameter is FALSE, automatic scrolling is 
disabled and calling TESelView has no effect. 


Scrap Handling 


The TEFromScrap and TEToScrap functions return a result code of type OSErr 
(defined as INTEGER in the Operating System Utilities) indicating whether an 
error occurred. If no error occurred, they return the result code 


CONST noErr = 0; {no error} 


Otherwise, they return an Operating System result code indicating an error. 
(See Appendix A for a list of all result codes.) 


FUNCTION TEFromScrap : OSErr; [Not in ROM] 


TEFromScrap copies the desk scrap to the TextEdit scrap. If no error occurs, it 
returns the result code noErr; otherwise, it returns an appropriate Operating 
System result code. 


Assembly-language note: From assembly language, you can store a handle to 
the desk scrap in the global variable TEScrpHandle, 
and the size of the desk scrap in the global 
variable TEScrpLength; you can get these values 
with the Scrap Manager function InfoScrap. 


FUNCTION TEToScrap : OSErr; [Not in ROM] 
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TEToScrap copies the TextEdit scrap to the desk scrap. If no error occurs, it 
returns the result code noErr; otherwise, it returns an appropriate Operating 
System result code. 

Warning: You must call the Scrap Manager function ZeroScrap to initialize 
the desk scrap or clear its previous contents before calling 
TEToScrap. 

Assembly-language note: From assembly language, you can copy the TextEdit 
scrap to the desk scrap by calling the Scrap Manager 
function PutScrap; you can get the values you need 
from the global variables TEScrpHandle and 
TEScrpLength. 

FUNCTION TEScrapHandle : Handle; [Not in ROM] 

TEScrapHandle returns a handle to the TextEdit scrap. 


Assembly-language note: The global variable TEScrpHandle contains a handle 
to the TextEdit scrap. 


FUNCTION TEGetScrapLen : LONGINT; [Not in ROM] 
TEGetScrapLen returns the size of the TextEdit scrap in bytes. 


Assembly-language note: The global variable TEScrpLength contains the size 
of the TextEdit scrap in bytes. 


PROCEDURE TESetScrapLen (length: LONGINT); [Not in ROM] 
TESetScrapLen sets the size of the TextEdit scrap to the given number of bytes. 


Assembly-language note: From assembly language, you can set the global 
variable TEScrpLength. 


FUNCTION GetStylScrap (hTE: TEHandle) : StScrpHandle; [Styled TextEdit] 

The GetStylScrap routine allocates a block of type StScrpRec and copies the 
style information associated with the current selection into it. This is the 
same as TECopy, except that no action is performed on the text, and the handle 
to the 'styl' scrap is output in this case. Unlike TECopy, the StScrpRec is not 
copied to the desk scrap. 


GetStylScrap will return a NIL value if called with an old style TEHandle, or if 
the selection is NIL (stylStart equals stylEnd). 


Note: See Macintosh Technical Note #207 for information on SetStylScrap. 


eeeClick on the X-Ref button, and refer to Technical Note #207.¢ee 


Advanced Routines 


PROCEDURE TECalText (hTE: TEHandle); 
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TECalText recalculates the beginnings of all lines of text in the edit record 

specified by hTE, updating elements of the lineStarts array. Call TECalText if 
you've changed the destination rectangle, the hText field, or any other field 

that affects the number of characters per line. 


Note: 


There are two ways to specify text to be edited. The easiest method 


is to use TESetText, which takes an existing edit record, creates a 
copy of the specified text, and stores a handle to the copy in the 
edit record. You can instead directly change the hText field of the 
edit record, and then call TECalText to recalculate the lineStarts 
array to match the new text. If you have a lot of text, you can use 


the latter method to save space. 


Assembly- language note: 


The global variable TERecal contains the address 


of the routine called by TECalText to recalculate 
the line starts and set the first and last characters 
that need to be redrawn. The registers contain the 


following: 
On entry A3: 
D7: 
On exit D2: 
D3: 
D4: 


Assembly- language note: 


pointer to the locked edit record 
change in the length of the 
record (word) 

line start of the line containing 
the first character to be 

redrawn (word) 

position of first character to be 
redrawn (word) 

position of last character to be 
redrawn (word) 


The global variable TEDoText contains the address 


of a multi-purpose text editing routine that advanced 
programmers may find useful. It lets you display, 
highlight, and hit-test characters, and position the 


pen to draw the caret. 


"Hit-test" means decide where 


to place the insertion point when the user clicks the 
mouse button; the point selected with the mouse is in 
the teSelPoint field. The registers contain the 


following: 
On entry A3: 
D3: 
D4: 
D7: 
On exit AO: 
DO: 


pointer to the locked edit record 
position of first character to be 
redrawn (word) 
position of last character to be 
redrawn (word) 
(word) @ to hit-test a character 
1 to highlight the selection 
range 
—1 to display the text 
—2 to position the pen to 
draw the caret 
pointer to current grafPort 
if hit-testing, character position 
or —1 for none (word) 
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FUNCTION TEGetOffset (pt: Point; hTE: TEHandle) : INTEGER; [Styled TextEdit] 


The TEGetOffset routine finds the character offset in an edit record's text 
corresponding to the given point. TEGetOffset works for both old-style and 
new-style edit records. 


FUNCTION TEGetPoint (offset: INTEGER; hTE: TEHandle) : POINT; [Styled TextEdit] 


The TEGetPoint routine returns the point corresponding to the given offset into 
the text. The point returned is to the bottom (baseline) left of the character 
at the specified offset. TEGetPoint works for both old- and new-style edit 
records. 


FUNCTION TEGetHeight (endLine, startLine: LONGINT; hTE: TEHandle) : INTEGER; 
[Styled TextEdit] 


The TEGetHeight routine returns the total height of all the lines in the text 
between and including startLine and endLine. TEGetHeight works for both old- and 
new-style edit records. 


PROCEDURE SetWordBreak (wBrkProc: ProcPtr; hTE: TEHandle); [Not in ROM] 


SetWordBreak installs in the wordBreak field of the specified edit record a 
special routine that calls the word break routine pointed to by wBrkProc. The 
specified word break routine will be called instead of TextEdit's default 
routine, as described under "The WordBreak Field" in the "Edit Records" section. 


Assembly-language note: From assembly language you don't need this 
procedure; just set the field of the edit record 
to point to your word break routine. 


PROCEDURE SetClikLoop (clikProc: ProcPtr; hTE: TEHandle); [Not in ROM] 


SetClikLoop installs in the clikLoop field of the specified edit record a 
special routine that calls the click loop routine pointed to by clikProc. The 
specified click loop routine will be called repeatedly as long as the user holds 
down the mouse button within the text, as described above under "The ClikLoop 
Field" in the "Edit Records" section. 


Assembly-language note: Like SetWordBreak, this procedure isn't necessary 
from assembly language; just set the field of the 
edit record to point to your click loop routine. 


Note: See Macintosh Technical Note #207 for information on TECustomHook, 
which provides TEEOLHook, TEWidthHook, TEDrawHook, and TEHitTestHook. 


eeeClick on the X-Ref button, and refer to Technical Note #207.¢ee 
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SUMMARY OF TEXTEDIT 


Constants 
CONST 
tejJustLeft = 0; { Text justification } 
teJustCenter = 1; 
teJustRight 7 -1; 
{[Styled TextEdit] } 
doFont = 1; {set font (family) number} 
doFace = 2; {set character style} 
doSize = 4; {set type size} 
doColor = 8; {set color} 
doALl = 15; {set all attributes} 
addSize = 16; {adjust type size} 
Data Types 
TYPE 
TEHandle = “*TEPtr; 
TEPtr = “TERec; 
TERec = RECORD 
destRect: Rect; {destination rectangle} 
viewRect: Rect; {view rectangle} 
selRect: Rect; {used from assembly language} 


lineHeight: INTEGER; {for line spacing} 
fontAscent: INTEGER; {caret/highlighting position} 


selPoint: Point; {used from assembly language} 
selStart: INTEGER; {start of selection range} 
selEnd: INTEGER; {end of selection range} 
active: INTEGER; {used internally} 

wordBreak: ProcPtr; {for word break routine} 
clikLoop: ProcPtr; {for click loop routine} 
clickTime: LONGINT; {used internally} 

clickLoc: INTEGER; {used internally} 


caretTime: LONGINT; {used internally} 
caretState: INTEGER; {used internally} 


just: INTEGER; {justification of text} 
teLength: INTEGER; {length of text} 
hText: Handle; {text to be edited} 


recalBack: INTEGER; {used internally} 
recalLines: INTEGER; {used internally} 
clikStuff: INTEGER; {used internally} 


crOnly: INTEGER; {if <Q, new line at Return only} 
txFont: INTEGER; {text font} 

txFace: Style; {character style} 

txMode: INTEGER; {pen mode} 

txSize: INTEGER; {font size} 
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inPort: GrafPtr; {grafPort} 


highHook: ProcPtr; {used from assembly Language} 
caretHook: ProcPtr; {used from assembly Language} 
nLines: INTEGER; {number of lines} 


lineStarts: ARRAY[@..16000] OF INTEGER 
{positions of line starts} 


END; 
CharsHandle = “*CharsPtr; 
CharsPtr = “Chars; 
Chars = PACKED ARRAY[0..32000] OF CHAR; 


{[Styled TextEdit] } 


TEStyleHandle = “TEStylePtr; 

TEStylePtr = “TEStyleRec; 

TEStyleRec = RECORD 
nRuns: INTEGER; {number of style runs} 
nStyles: INTEGER; {number of distinct styles } 

{ stored in style table} 

styleTab: STHandle; {handle to style table} 
LhTab: LHHandle; {handle to line-height table} 
teRefCon: LONGINT; {reserved for application use} 


nullStyle: nullSTHandle; {handle to style set } 
{ at null selection} 
runs: ARRAY [0..0] OF StyleRun 
END; 


StyleRun = RECORD 
startChar: INTEGER; {starting character position} 
styleIndex: INTEGER {index in style table} 


END; 
STHandle = “STPtr; 
STPtr = “TEStyleTable; 
TEStyleTable = ARRAY [0..0] OF STElement; 
STELement = RECORD 
stCount: INTEGER; {number of runs in this style} 
stHeight: INTEGER; {line height} 
stAscent: INTEGER; {font ascent} 
stFont: INTEGER; {font (family) number} 
stFace: Style; {character style} 
stSize: INTEGER; {size in points} 
stColor: RGBColor {absolute (RGB) color} 
END; 
LHHandle = “LHPtr; 
LHPtr = “LHTable; 
LHTable = ARRAY [0..0] OF LHElement; 
LHElement = RECORD 
LUhHeight: INTEGER; {maximum height in line} 
LhAscent: INTEGER {maximum ascent in line} 
END; 


NullSTHandle = “NullSTPtr; 
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NullSTPtr = “NullSTRec; 
NullLSTRec = RECORD 
TEReserved: LONGINT; {reserved for future } 
{ expansion} 
nullScrap: STScrpHandle {handle to scrap style } 
{ table} 
END; 
TextStyle = RECORD 
tsFont: INTEGER; {Font (family) number} 
tsFace: Style; {Character style} 
tsSize: INTEGER; {Size in points} 
tsColor: RGBColor {Absolute (RGB) color} 
END; 
StScrpHandle = *“StScrpPtr; 
StScrpPtr = “StScrpRec; 
StScrpRec = RECORD 
scrpNStyles: INTEGER; {number of distinct } 
{ styles in scrap} 
scrpStyleTab: ScrpSTTable {table of styles for scrap} 
END; 
ScrpSTTable = array [0..0] of ScrpSTElement; 
ScrpSTElement = RECORD 
scrpStartChar: LONGINT; {offset to start of style} 
scrpHeight: INTEGER; {line height} 
scrpAscent: INTEGER; {font ascent} 
scrpFont: INTEGER; {font (family) number} 
scrpFace: Style; {character style} 
scrpSize: INTEGER; {size in points} 
scrpColor: RGBColor; {absolute (RGB) color} 
END; 
Routines 


Initialization and Allocation 


PROCEDURE TEInit; 

FUNCTION TENew (destRect,viewRect: Rect) : TEHandle; 

FUNCTION TEStylNew (destRect,viewRect: Rect) : TEHandle; [Styled TextEdit] 
PROCEDURE TEDispose (hTE: TEHandle); 


Accessing the Text or Style Information of an Edit Record 


PROCEDURE TESetText (text: Ptr; length: LONGINT; hTE: TEHandle); 
FUNCTION TEGetText (hHTE: TEHandle) : CharsHandle; 


[Styled TextEdit additions] 


PROCEDURE TEGetStyle (offset: INTEGER; VAR theStyle: TextStyle; 

VAR LineHeight,fontAscent: INTEGER; hTE: TEHandle); 
PROCEDURE SetStylHandle (theHandle: TEStyleHandle; hTE: TEHandle) ; 
FUNCTION GetStylHandle (hTE: TEHandle) : TEStyleHandle; 
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Insertion Point and Selection Range 

PROCEDURE TEIdle (hTE: TEHandle) ; 

PROCEDURE TEClick (pt: Point; extend: BOOLEAN; hTE: TEHandle); 

PROCEDURE TESetSelect (selStart,selEnd: LONGINT; hTE: TEHandle); 

PROCEDURE TEActivate (hHTE: TEHandle); 

PROCEDURE TEDeactivate (hTE: TEHandle); 

Editing 

PROCEDURE TEKey (key: CHAR; hTE: TEHandle); 

PROCEDURE TECut (hTE: TEHandle) ; 

PROCEDURE TECopy (hHTE: TEHandle); 

PROCEDURE TEPaste (hHTE: TEHandle); 

PROCEDURE TEStylPaste (hTE: TEHandle); [Styled TextEdit] 

PROCEDURE TEDelete (hHTE: TEHandle); 

PROCEDURE TEInsert (text Ptr; Length: LONGINT; hTE: TEHandle); 

PROCEDURE TEStylInsert (text: Ptr; Length: LONGINT; hST: stScrpHandle; 
hTE: TEHandle); [Styled TextEdit] 

PROCEDURE TEReplaceStyle (mode: INTEGER; oldStyle,newStyle: TextStyle; 


redraw: BOOLEAN; hTE: TEHandle); [Styled TextEdit] 
(mode: INTEGER; newStyle: TextStyle; redraw: BOOLEAN; 
hTE: TEHandle); [Styled TextEdit] 


PROCEDURE TESetStyle 


Text Display and Scrolling 


PROCEDURE TESetJust (just: INTEGER; hTE: TEHandle); 
PROCEDURE TEUpdate (rUpdate: Rect; hTE: TEHandle); 
PROCEDURE TextBox (text: Ptr; length: LONGINT; box: Rect; 
just: INTEGER); 
PROCEDURE TEScroll (dh,dv: INTEGER; hTE: TEHandle); 
[Volume IV additions] 
PROCEDURE TESelView (hHTE: TEHandle); 
PROCEDURE TEPinScroll (dh,dv: INTEGER; hTE: TEHandle); 
PROCEDURE TEAutoView (auto: BOOLEAN; hTE: TEHandle); 
Scrap Handling [Not in ROM] 
FUNCTION TEFromScrap OSErr; 
FUNCTION TEToScrap : OSErr; 
FUNCTION TEScrapHandle : Handle; 
FUNCTION TEGetScrapLen : LONGINT; 
PROCEDURE TESetScrapLen : (length: LONGINT); 
FUNCTION GetStylScrap (hTE: TEHandle) : StScrpHandle; [Styled TextEdit] 
Advanced Routines 
PROCEDURE TECalText (hHTE: TEHandle); 
FUNCTION TEGetOffset (pt: Point; hTE: TEHandle) : INTEGER; [Styled TextEdit] 
FUNCTION TEGetPoint (offset: INTEGER; 
hTE: TEHandle) : POINT; [Styled TextEdit] 
FUNCTION TEGetHeight (endLine, startLine: LONGINT; 
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hTE: TEHandle) : INTEGER; [Styled TextEdit] 
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PROCEDURE SetWordBreak (wBrkProc: ProcPtr; hTE: TEHandle); [Not in ROM] 
PROCEDURE SetClikLoop (clikProc: ProcPtr; hTE: TEHandle); [Not in ROM] 


Word Break Routine 


FUNCTION MyWordBreak (text: Ptr; charPos: INTEGER) : BOOLEAN; 


Click Loop Routine 


FUNCTION MyClikLoop : BOOLEAN; 


Assembly-Language Information 
Constants 


Text justification 


teJustLeft . EQU 0 
teJustCenter .EQU 1 
tejJustRight .EQU -1 


[Styled TextEdit additions] 


Set/Replace style modes 


fontBit EQU 0 sset font 

faceBit EQU 1 sset face 

sizeBit EQU 2 sset size 

clrBit EQU 3 sset color 

addSizeBit EQU 4 sadd size mode 
teStylesH EQU teFont ;replaces teFont/teFace 


Offsets into TEStyleRec 


nRuns EQU 0 ; [integer] # of entries in styleStarts array 
nStyles EQU 2 ; [integer] # of distinct styles 

styleTab EQU 4 ; [STHandle] handle to distinct styles 

LhTab EQU 8 ; [LHHandle] handle to line heights 


teRefCon EQU 12 ;[longint] reserved 
nullStyle  EQU 16 ; [nul lLSTHandle] Handle to style set at null selection 
runs EQU 20 ;array of styles 


Offsets into StyleRun array 


startChar EQU 0 ; [INTEGER] offset into text to start of style 
styleIndex  EQU 2 ; [INTEGER] style index 
stStartSize EQU 4 ;size of a styleStarts entry 


Offsets into STElement 
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stCount EQU 0 ; [integer] # of times this style is used 
stHeight EQU 2 ; [integer] line height 

stAscent EQU 4 ; [integer] ascent 

stFont EQU 6 ; [integer] font 

stFace EQU 8 ; [style] face 

stSize EQU 10 ; [integer] size 


stColor EQU 12 ; [RGBColor] color 
stRecSize EQU 18 ;size of a teStylesRec 


Offsets into TextStyle 


tsFont EQU 0 ; [integer] font 
tsFace EQU 2 ; [style] face 
tsSize EQU 4 ; [integer] size 
tsColor EQU 6 ; [RGBColor] color 


styleSize EQU 12 ;size of a StylRec 
Offsets into StScrpRec 


scrpNStyles EQU 0 ; [integer] # of styles in scrap 
scrpStyleTab  EQU 2 ;[ScrpSTTable] start of scrap styles array 


Offsets into scrpSTElement 


scrpStartChar EQU 0 ;[longint] char where this style starts 
scrpHeight EQU 4 ; [integer] line height 
scrpAscent EQU 6 ; [integer]ascent 

scrpFont EQU 8 ; [integer] font 

scrpFace EQU 10 ; [style] face 

scrpSize EQU 12 ; [integer]size 

scrpColor EQU 14 ; [RGBColor] color 
scrpRecSize EQU 20 ;size of a scrap record 

Edit Record Data Structure 

teDestRect Destination rectangle (8 bytes) 
teViewRect View rectangle (8 bytes) 

teSelRect Selection rectangle (8 bytes) 

teLineHite For line spacing (word) 

teAscent Caret/highlighting position (word) 
teSelPoint Point selected with mouse (long) 
teSelStart Start of selection range (word) 

teSelEnd End of selection range (word) 

teWordBreak Address of word break routine (see below) 
teClikProc Address of click loop routine (see below) 
teJust Justification of text (word) 

teLength Length of text (word) 

teTextH Handle to text 

teCROnly If <0, new line at Return only (byte) 
teFont Text font (word) 

teFace Character style (word) 

teMode Pen mode (word) 

teSize Font size (word) 
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teGrafPort Pointer to grafPort 


teHiHook Address of text highlighting routine (see below) 
teCarHook Address of routine to draw caret (see below) 
teNLines Number of lines (word) 

teLines Positions of line starts (teNLines*2 bytes) 
teRecSize Size in bytes of edit record except teLines field 


Word break routine 
On entry AQ: pointer to text 
DO: character position (word) 
On exit Z condition code: 0 to break at specified character 
1 not to break there 
Click loop routine 


On exit DO: 1 
D2: must be preserved 


Text highlighting routine 

On entry A3: pointer to locked edit record 

Caret drawing routine 

On entry A3: pointer to locked edit record 

Variables 

TEScrpHandle Handle to TextEdit scrap 

TEScrpLength Size in bytes of TextEdit scrap (word) 

TERecal Address of routine to recalculate line starts (see below) 


TEDoText Address of multi-purpose routine (see below) 


TERecal routine 


On entry A3: pointer to locked edit record 
D7: change in length of edit record (word) 
On exit D2: line start of line containing first character to be 


redrawn (word) 
D3: position of first character to be redrawn (word) 
D4: position of last character to be redrawn (word) 


TEDoText routine 


On entry A3: pointer to locked edit record 
D3: position of first character to be redrawn (word) 
D4: position of last character to be redrawn (word) 
D7: (word) 0 to hit-test a character 
1 to highlight selection range 
-—1 to display text 
—2 to position pen to draw caret 
On exit AQ: pointer to current grafPort 
DO: if hit-testing, character position or —1 for none (word) 
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Further Reference: 


QuickDraw 

Toolbox Event Manager 

Window Manager 

Font Manager 

Script Manager 

Technical Note #18, TextEdit Conversion Utility 

Technical Note #22, TEScroll Bug 

Technical Note #72, Optimizing for the LaserWriter — Techniques 
Technical Note #82, TextEdit: Advice & Descent 

Technical Note #127, TextEdit EOL Ambiguity 

Technical Note #203, Don't Abuse the Managers 

Technical Note #207, Styled TextEdit Changes in System 6.0 
Technical Note #237, TextEdit Record Size Limitations Revisited 


END OF DOCUMENT 
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